ZK In An Embedded Equinox In An Existing Servlet Container

Author
Mirko Bernardoni, Software Architect at Steria PSF

Mirko is an Architect with almost twelve years of experience in information technology. Mirko’s main interests are parallel computing, multi-thread programming and cluster system, computer science engineering applications and physics, studying (especially scientific problems).

Date
April 05, 2012

Version
ZK 6.0

Introduction

The Equinox project has a server side effort that seeks to integrate the dynamic module capabilities of OSGi into standard application server scenarios [2].

There are two main approaches; embedding Equinox in the servlet container or embedding the servlet container in Equinox.

The following two diagrams illustrate the Equinox approach.

Figure 1: Equinox runs an application container

In Figure 1, the approach is turned around and Equinox runs an application container (e.g., embedded Jetty) and provides some glue code that wires Equinox-based applications into the application container. This scenario is suggested for development.

Figure 2: Equinox is embedded in an existing servlet container

Equinox is embedded in an existing servlet container as shown in Figure 2 by installing a very thin web application. This application contains a Bridge Servlet that launches an Equinox instance inside the application and then forwards all requests to the Equinox-based application. This is our scenario for production environment.

If you are not familiar with OSGi it is recommended to read OSGi introduction , Developing plug-in based applications with OSGi and Develop ZK application in OSGi Framework before reading this small talk.

This system's configuration is for the production environment. You can also use this configuration for development but it's not so convenient because of the deployment procedure for every change on the source code. A good idea is to test your application in this configuration just to see if every is fine, and to develop in an embedded HTTP server in Equinox. This solution is good if you don't know the production application server or if your production application server is not OSGi compliant. This configuration is developed (at the moment) without the ZK plus package.

Embed Equinox in an existing servlet container

From the server point of view, every OSGi resources are in a jar. file. In fact we can't use the normal servlet resolution to access a resource, we must leverage OSGi functionality.

As ZK is not designed to work in an OSGi container, for adding this capability we need to patch some source (class loader and resource loader).

Directory structure

Create a new Dynamic web module project.

The general idea is to create a WAR file structured as follows:

/WEB-INF

/web.xml with one servlet entry assigning all incoming requests to the BridgeServlet

/eclipse the eclipse platform directory

launch.ini contains framework properties that will allow override of any eclipse specific System Properties

/configuration contains config.ini which lists the availability of the bundles you want to have

/features contains all the feature bundles

/plugins contains all the bundles needed for launch the application

Copy in WEB-INF/lib zk_equinox_bridge.jar

This jar contains the bridge classes from equinox servlet bridge patched for the ZK listener to work.

Copy in WEB-INF/eclipse/plugins, the content of bundles.zip are the dependency bundles.

The dependency bundles contains all the bundles necessary for running the example. This bundle was downloaded from Springsource, Eclipse Orbit or can be created with the procedure described in Develop ZK application in OSGi Framework.

Copy in WEB-INF/eclipse/plugins the content of bundles-zk6.zip

This zip contains ZK jars patched for OSGi.

Copy in WEB-INF/eclipse/plugins the bundle [3]

This is the library helper for the creation of a new ZK OSGi bundle.

Now you need to set your target platform for permit at the java compiler to see our bundles.

Our target folder is WEB-INF/eclipse/plugins

Creation of a bundle

The request route shown in Figure 2:

1. The request arrives at the application server
2. The application server routes the request to the servlet bridge
3. The servlet bridge searches for a registered http service
4. The http service routes the request to the ZK servlet.

The work is done by zk_equinox_servlet_bridge.jar and org.zkoss.osgi.equinox bundle.

We simple create an Activator in the main bundle as:

 
public class Activator implements BundleActivator {

	private BundleContext context;
	private ServletRegister tracker;

	public BundleContext getContext() {
		return context;
	}

	@Override
	public void start(BundleContext bundleContext) throws Exception {
		this.context = bundleContext;
		this.tracker = new ServletRegister(bundleContext, "/zk", "/web");
		this.tracker.open();
	}

	@Override
	public void stop(BundleContext bundleContext) throws Exception {
		this.context = null;
		this.tracker.close();
	}

}

In the start method, we map the web URL /ZK to the bundle path /web. Now you can create your own bundle plugin, or simply unpack and import the content of bundle_samples.zip. It's a ZK application written to test the Zk OSGi system.

Deploy and Run

• Right click on your packages to deploy, select export.

• Select export as "Deployable plug-ins and fragments", and click next.

• Select the bundles (plugins) to export. Select the directory as WEB-INF/eclipse. The bundles will be copied into the plugins directory automatically. Click finish.
• Now select your Dynamic web module project and do a refresh, just to tell your eclipse that there are new files inside the plugins directory.
• Now run your Dynamic web project, and you can see the test page
• If you are using the example the url is http://localhost:8080/osgi/zk/index.html

The long way: apply the patch yourself

Download at [4] for the source code patch.

Download ZK 6.0 source code, and merge the patch with the source code manually.

The patch modifies the following files:

1. All the Manifest.mf files
2. in the package org.zkoss.zk.zweb the ResourceCaches class
3. In the package org.zkoss.zk.zcommon: add the new Activator class and modify the ClassLocator classs and the Classes class
4. In the package org.zkoss.zk.zk the BSHInterpreter.GlobalNS class

For agile exporting in the bundle version, it's also necessary to move all the metainfo and web packages to the bundle's root and export them as a folder in the main bundle's root.

The next procedure will be export all the ZK's package as plug-ins, see the deploy paragraph for how.

Limitations

• The current implementation allows only one zk url path mapped for web application.
• The index.zul default page doesn't work.
• If the page doesn't exist, the zul interpreter shows an exception: you can't see the 404 error.
• There isn't support for the ZK plus package.

What's next

Support for other OSGi frameworks like Felix.

Support for ZK Plus.

Download

You can download the sample application code and the libraries from Zk-OSGi

Reference

Special thanks to Giovanni Ganassin for the encouragement and the support over ZK.

Comments

Copyright © Potix Corporation. This article is licensed under GNU Free Documentation License.